package sjtu.rfid.rri.services.queue;

/**
 * This interface defines the basic operations of queues.
 * 
 * @author jinghao
 * 
 */

public interface Queue {

	/**
	 * Adds a queueListener to the set of queueListeners for this queue,
	 * provided that it is not the same as some queueListener already in the
	 * set. The order in which notifications will be delivered to multiple
	 * queueListeners is in the order of adding in .
	 * 
	 * @param queueListener
	 *            an QueueListener to be added.
	 * @return true if added successfully, false if not
	 * @throws NullPointerException
	 *             if the parameter queueListener is null.
	 */
	public boolean addQueueListener(QueueListener queueListener);

	/**
	 * Removes a queueListener from the set of queueListeners of this object.
	 * Passing <CODE>null</CODE> to this method will have no effect.
	 * 
	 * @param queueListener
	 *            the observer to be removed.
	 * @return true if removed successfully, false if not
	 */
	public boolean removeQueueListener(QueueListener queueListener);

	/**
	 * Clear all queueListeners from the set of queueListeners of this object.
	 */
	public void clearQueueListener();

	/**
	 * Add data into the queue
	 * 
	 * @param data
	 */
	public void add(Object data) throws QueueException;

	/**
	 * Close the queue, it will stop the queue from sending data any more. <br>
	 * As the queue is designed to be a shared one, user should always call
	 * QueueFactory.close() method to close queue instead of call this method
	 * directly. If this method is called directly, the result maybe unknown.
	 * 
	 * @throws QueueException
	 *             if failed to close the queue.
	 */
	public void close() throws QueueException;

	// //////////////////////////////////////
	// ////////////// Misc Methods /////////
	// /////////////////////////////////////

	/**
	 * clear the items of the queue
	 * 
	 */
	public void clear();

	/**
	 * @return lastest time of tag received
	 */
	public long getLastTagTime();

	/**
	 * 
	 * @return the name of the Queue
	 */
	public String getQueueName();
}
